CONTROL ADD LISTBOX statement

Purpose

Add a list box control to a dialog. A list box contains a set of predefined entries that permit a user to select one or more items. A list box may contain strings, images, or both. To put numbers in a list box, convert them to strings with the FORMAT$, USING$, or STR$ functions.

Syntax

CONTROL ADD LISTBOX, hDlg, id&, [items$()], x, y, xx, yy [, [style&] [, [exstyle&]]] [[,] CALL callback]

hDlg

Handle of the dialog in which the list box will be created. The dialog will become the parent of the control.

id&

Unique identifier for the control in the range 1 to 65535, frequently specified with numeric equates for clarity of the code. For example, the equate %PickList is more informative than a literal value such as 497. Best practice suggests identifiers should start at 100 to avoid conflict with any of the standard predefined identifiers.

items$()

Optional dynamic (variable length) string array containing the initial items to be displayed in the list box. Items are copied from the array to the list box, starting at the lowest subscript of the array (LBOUND), continuing on toward the end of the array until an empty string is encountered, or the highest subscript is reached. If an array with an LBOUND of zero (the default) is specified, be sure that the 1st element (0) contains data. Also see Restrictions below.

To create a list box that is initially empty, either omit this parameter, or specify an array whose first element contains an empty string. If the list box uses the %LBS_SORT style, the items are sorted alphanumerically as they are added to the list box.

x, y

Integer expressions, variables, or numeric literal values, specifying the location of the control inside the dialog client area. x is the horizontal position, and y is the vertical position. 0,0 refers to the upper left corner of the dialog box client area. Coordinates are specified in the same terms (pixels or dialog units) as the parent dialog.

Integral expression, variable, or numeric literal value, specifying the width of the control. The width is given in the same terms (pixels or dialog units) as the parent dialog. The most common value used in the Microsoft Dialog Editor and Visual Studio is 100 dialog units.

Integral expression, variable, or numeric literal value, specifying the height of the control. The height is given in the same terms (pixels or dialog units) as the parent dialog. The most common value used in the Microsoft Dialog Editor and Visual Studio is 40 dialog units.

style&

Primary style of the list box control. The default list box style comprises %LBS_SORT, %LBS_NOTIFY, %WS_TABSTOP, and %WS_VSCROLL (along with the %WS_EX_CLIENTEDGE extended style). The default list box style is used if both the primary and extended style parameters are omitted from the statement. For example:

CONTROL ADD LISTBOX, hDlg, id&, items$(), 100, 100, 150, 200, , , _

CALL ListboxCallback() ' Use default styles

Custom style values replace the default values. That is, they are not additional to the default style values - your code must specify all necessary primary and extended style parameters.

The primary list box style value can be a combination of any values below, combined together with the OR operator to form a bitmask:

%LBS_DISABLENOSCROLL	Show a disabled vertical scroll bar in the list box when the box does not contain enough items to scroll. Without this style, the scroll bar is hidden when the list box does not contain enough items. Used in conjunction with the %WS_VSCROLL style.
%LBS_EXTENDEDSEL	Allow selection of multiple items in the list box by using the SHIFT key with mouse and/or keyboard actions.
%LBS_MULTICOLUMN	List box has multiple columns, and can be scrolled horizontally. To set the width, send the %LB_SETCOLUMNWIDTH message to the list box control.
%LBS_MULTIPLESEL	Allow selection of multiple items in the list box (without needing to use the SHIFT key) with mouse and/or keyboard actions.
%LBS_NOINTEGRALHEIGHT	Force the size of the list box to be exactly the size specified when the control is created. Otherwise, Windows may resize the list box to ensure that items are not partially displayed (clipped).
%LBS_NOSEL	The list box can contain items that can be viewed but not selected.
%LBS_NOTIFY	Send the callback a message whenever the user clicks or double-clicks a string in the list box.
%LBS_SORT	Automatically sort strings added to the list box in alphanumeric order.
%LBS_STANDARD	Equivalent to the combination of %LBS_SORT, %LBS_NOTIFY, %WS_VSCROLL and %WS_BORDER styles.
%LBS_USETABSTOPS	Expand tab ($TAB, CHR$(9)) characters. The default tab positions are for every 32 dialog units. To change the tab stop positions, send the %LB_SETTABSTOPS message to the list box control.
%WS_DISABLED	Create a control that is initially disabled. A disabled control cannot receive input from the user.
%WS_HSCROLL	Allow the control to display a horizontal scroll bar. By default this is disabled unless the controls horizontal scroll width has been configured by sending a %LB_SETHORIZONTALEXTENT message to the control. Use in conjunction with %LBS_DISABLENOSCROLL to make the scroll bar(s) visible at all times.
%WS_GROUP	Define the start of a group of controls. The first control in each group should also use %WS_TABSTOP style. The next %WS_GROUP control in the tab order defines the end of this group and the start of a new group.
%WS_TABSTOP	Allow the control to receive keyboard focus when the user presses the TAB and SHIFT+TAB keys. The TAB key shifts keyboard focus to the next control with the %WS_TABSTOP style, and SHIFT+TAB shifts focus to the previous control with %WS_TABSTOP. (default)
%WS_VSCROLL	Allow the control to display a vertical scroll bar if the list is longer than the height of the list box. Use in conjunction with %LBS_DISABLENOSCROLL to make the scroll bar(s) visible at all times.

Do not intermix list box styles with similarly named combo box styles as the numeric values of similar styles can produce unexpected results. For example, %LBS_SORT =&H2 and %CBS_SORT = &H100. List box styles are prefixed with %LBS.

exstyle&

Extended style of the list box control. The default extended list box style comprises %WS_EX_CLIENTEDGE, and %WS_EX_LEFT. The default extended style is used if both the primary and extended parameters are omitted from the CONTROL ADD LISTBOX statement, in the same manner as style& above.

The extended list box style value can be a combination of any values below, combined together with the OR operator to form a bitmask:

%WS_EX_CLIENTEDGE	Apply a sunken edge border to the control.
%WS_EX_LEFT	The control has generic "left-aligned" properties. (default)
%WS_EX_RIGHT	The control has generic "right-aligned" properties. This style has an effect only if the shell language is Hebrew, Arabic, or another language that supports reading order alignment; otherwise, the style is ignored.
%WS_EX_STATICEDGE	Apply a three-dimensional border style to the control (intended to be used for items that do not accept user input).
%WS_EX_TRANSPARENT	Controls/windows beneath the control are drawn before the control is drawn. The control is deemed transparent because elements behind the control have already been painted - the control itself is not drawn differently. True transparency is achieved by using Regions - see MSDN for more information.
%WS_EX_WINDOWEDGE	Apply a raised edge border to the control.

callback

Optional name of a Callback Function that receives all %WM_COMMAND and %WM_NOTIFY messages for the control. See the #MESSAGES metastatement to choose which messages will be received. If a callback for the control is not designated, you must create a dialog Callback Function to process messages from your control.

If the Callback Function processes a message, it should return TRUE (non-zero) to prevent the message being passed unnecessarily to the dialog callback (if one exists). The dialog callback should also return TRUE if the notification message is processed by that Callback Function. Otherwise, the DDT engine processes unhandled messages.

Remarks

The following notifications are sent to the Callback Function:

%LBN_DBLCLK	Sent when the user double-clicks a string in the list portion of a list box.
%LBN_ERRSPACE	Sent when a list box cannot allocate enough memory to meet a specific request.
%LBN_KILLFOCUS	Sent when a list box loses the keyboard focus.
%LBN_SELCANCEL	Sent when the user selects an item, but then selects another control or closes the dialog box. It indicates the user's initial selection is to be ignored.
%LBN_SELCHANGE	Sent when the selection in the list box is about to be changed as a result of the user either clicking in the list box or changing the selection by using the arrow keys.
%LBN_SETFOCUS	Sent when a list box receives the keyboard focus.

When a Callback Function receives a %WM_COMMAND message, it should explicitly test the value of CB.CTL and CB.CTLMSG to guarantee it is responding appropriately to the notification message.

Restrictions

Under Windows 95/98/ME, a list box is limited to 32,736 items. In all versions of Windows, the actual string data contained by the list box is limited only by available memory.